perm filename DISPLY.RBN[UP,DOC]1 blob
sn#002775 filedate 1972-10-06 generic text, type T, neo UTF8
NEELEY DISPLAY ROUTINES
This file contains documentation for:
Fortran and Sail display routines
PLTVEC --- The Vector Plotter
PIXPEN --- The Display Editor
FORTRAN AND SAIL ACCESSABLE DISPLAY ROUTINES
NOTE: Most of these routines do things to the user's display
buffers, and have no immediate affect on the current state of
the display. The four exceptions are: DPYTYP and TYPLOC,
which control the user's type-out; DPYOUT, which causes a
buffer to be displayed; HYDPOG, which inhibits temporarily
the displaying of a buffer; and DPYCLR, which returns the
display to its normal state.
CALL DPYSET(<piece of glass>,<buffer address>,<buffer size>)
Set up a correspondence between the piece of glass number
indicated and a buffer. Legal piece of glass numbers run
from 0 through 14 (decimal). Piece of glass 15 is legal, but
by convention it is reserved for Raid. For Sail, <buffer
address> must be the first element of an array (e.g. A[1]),
and not simply an array name. For Fortran, it doesn't
matter. DPYSETs subsequent to the first serve to clear the
buffer to which they refer. DPYSET puts the initial word
count (which is always 2) into <buffer address> + 1 (e.g.
A[2]). All other display routines that affect the buffer
update this count.
CALL DPYCLR
Returns display to normal state (i.e., like when you logged
in).
CALL CLRPOG(<piece of glass>)
Resets the buffer associated with the piece of glass number
to its state immediately after the dpyset was performed on
it.
CALL HYDPOG(<piece of glass>)
Stops displaying the piece of glass without affecting the
buffer. A subsequent DPYOUT on this buffer will restart the
display.
CALL SETPOG(<piece of glass>)
Specifies that calls on display functions to follow refer to
the piece of glass indicated. DPYSET performs an implicit
SETPOG.
CALL ACCPOG(<piece of glass>)
This allows display buffer I/O. The procedure for output is:
1. Create a display. 2. Write the buffer in binary mode. For
input: 1. Do a dpyset on some buffer. 2. Read a display file
into the buffer in binary mode. (Hint: Use the second word
read in -- the word count -- to determine how many more words
to read.) 3. Call ACCPOG using the piece of glass that was
specified in the dpyset.
CALL NORELOPT
Inhibits the replacement of a relative vector by a short
vector.
CALL RELOPT
Allows relative vectors to be optomized. RELOPT is the
default condition.
CALL AVECT(X,Y)
Draws an absolute (visible) vector to (X,Y).
CALL AIVECT(X,Y)
Draws an absolute invisible vector to (X,Y).
CALL RVECT(X,Y)
Draws a relative (visible) vector to (X,Y). If both
parameters of a relative vector or point are within the range
required for short vectors and optomization has not been
inhibited by a NORELOPT, a short vector will automatically be
drawn.
CALL RIVECT(X,Y)
Draws a relative invisible vector to (X,Y).
CALL SVECT(X,Y)
Draws a relative (visible) vector to (X,Y) using short vector
words. Vectors drawn with short vector words must have both
arguments in the range -64 to 63.
CALL SIVECT(X,Y)
Draws a relative invisible vector to (X,Y) using short vector
words.
CALL APOINT(X,Y)
Plots a point at absolute location (X,Y).
CALL RPOINT(X,Y)
Plots a point at relative location (X,Y).
CALL SPOINT(X,Y)
Plots a point at relative location (X,Y) using short vector
words.
A = AVECW(X,Y)
Puts an absolute (visible) vector to (X,Y) in A.
A = AIVECW(X,Y)
Puts an absolute invisible vector to (X,Y) in A.
A = RVECW(X,Y)
Puts a relative (visible) vector to (X,Y) in A.
A = RIVECW(X,Y)
Puts a relative invisible vector to (X,Y) in A.
A = APOINW(X,Y)
Puts an absolute endpoint vector to (X,Y) in A.
A = RPOINW(X,Y)
Puts a relative endpoint vector to (X,Y) in A.
CALL ALINE(X1,Y1,X2,Y2)
This is equivalent to:
CALL AIVECT(X1,Y1)
CALL AVECT(X2,Y2)
CALL RLINE(X1,Y1,X2,Y2)
This is equivalent to:
CALL AIVECT(X1,Y1)
CALL RVECT(X2,Y2)
CALL DPYTYP(<position>,<no. of jumps>,<no. of lines/jump>)
Sets the top of page-printer type-out to <position>, where
-512 (decimal) specifies the bottom of the screen, and 512
specifies the top. Sets the number of lines typed before any
are thrown off the top of the type-out to N, where N is <no.
of lines/jump>, and sets the number of N-line groups
displayed to <no. of jumps>.
CALL TYPLOC(<top of type-out>,<bottom of type-out>)
Sets the top and bottom of page-printer type-out to the
indicated positions. The <no. of jumps> defined above is set
to one.
CALL DPYBRT(N)
Sets brightness to N (1 ≤ N ≤ 7). This affects vectors
subsequently included in the current piece of glass (as well
as vectors in pieces of glass whose numbers are greater than
the current one) until another DPYBRT is issued.
CALL DPYBIG(N)
Sets character size to N (1 ≤ N ≤ 7). This has the same
affect on characters as DPYBRT has on vectors. Standard size
is 2.
DPYSTR(<string>)
(Gogol only)
Displays the string specified.
DPYVST(X,Y,<string>)
(Gogol only)
Equivalent to:
AIVECT(X,Y)
DPYSTR(<string>)
DPYSST(<string>)
(Sail only)
Displays the string specified.
DPYSVS(X,Y,<string>)
(Sail only)
Equivalent to:
AIVECT(X,Y)
DPYSST(<string>)
CALL DPYTXT(<text>,<word count>) or
CALL DPYTXT(X,Y,<text>,<word count>)
(Fortran only)
The parameter <text> may be a variable or array, or a
literal. Characters will be displayed from the beginning of
<text> until a total of <word count> words have been
displayed. If X and Y are specified, then does an AIVECT(X,Y)
before displaying the text.
CALL DPYOUT(<piece of glass>)
Displays the piece of glass indicated.
PLTVEC -- THE VECTOR PLOTTER
PURPOSE
It is now possible to plot a display buffer that has been generated
by the FORDPY routines. PLTVEC reads a disk file in binary buffered
mode (octal 13 or 14) and interprets it as a display buffer.
BASIC USE
PLTVEC will first demand two pieces of information from you:
1. Points: regular, dashed, or vectors. If you reply "R", then any
endpoint vectors in the file will be plotted as bona fide
points -- the pen will be moved to the point location in the
up position and will then be lowered at that location. If you
reply "D", then endpoint vectors will be alternately turned
into visible and invisible vectors. If the buffer has many
consecutive points and they are close together, then the
effect of this mode is reasonable. If you reply "V" then all
points are plotted as visible vectors.
2. Scale factor. If you type carriage return to this query, then the
display buffer gets plotted approximately the same size as it
appeared on the display screen. Otherwise, a real number or
integer may be typed, and the size of the plot will be
multiplied by this scale factor. This number may be either
less than, equal to, or greater than one. In a paragraph
below, the term "frame width (heigth)" is used. This term is
defined as the width of a DPY screen (about 14 inches)
multiplied by the scale factor.
PLTVEC will then repeatedly request two additional pieces of
information:
1. File name. This may be any disk file that consists of a display
buffer.
2. Displace frame. You may move the position of the display frame
either left, right, up, or down by typing "L", "R", "U", or
"D", respectively. The frame will be moved one frame width
(height) plus a small margin. You can get this effect repeated
as many times as you like by typing several characters in this
line. For example, if you type "ULLLU" then the pen will be
moved up one frame height, then left three frame widths, and
finally one more frame height up. If you type a number
immediatly before any of these four characters, then its
meaning is changed. The number is interpreted as the number
of inches you want the pen moved in the particular direction.
The number may be either an integer or a real number
(containing a decimal fraction). Thus, if you type "R20U5.67L"
then the pen will be moved right one frame width, up 20
inches, and left 5.67 inches.
INDIRECT FEATURE
If you type @<file name> to the file name request, then PLTVEC will
begin accepting information from the STOPGAP file whose name you
typed. Each piece of information should be on a separate line. The
two pieces of information for each display file must appear on
consecutive lines in the STOPGAP file in the order given above.
PIXPEN IS HERE!
PIXPEN is a display editor for III displays that uses the light pens
for drawing. Following are the commands you may give from the
kayboard. Lower case letters are converted to upper case upon input
(except in text mode), and so they may be used for all commands.
Carriage returns are not necessary to terminate commands, unless
otherwise specified. To move the cursor (which will be the only
thing displayed immediately after initialization), point the light
pen at the center of the cursor within a reasonable distance from the
screen (not more than two or three inches). Then press the button on
the side of the pen and move it across the face of the display
screen. If you have a hard time getting the cursor to follow the
pen, try holding the pen closer to the screen, or turning off the
room lights.
0. Initialization.
When you run PIXPEN, the display "PIXPEN / Stanford A. I. Project
Display Editor" will be flashed on the screen, and the query "How big
do you want your display buffer?" will be typed. This display will
normally last for about a half second, and then will go away.
However, if you type a space while the display is on the screen, it
will stay there. You may then specify your buffer size, which may
not be less than 20 nor more than 2000. If you just type carriage
return then you get the default size (as you do if you type nothing),
which is 1024.
1. Drawing.
The commands described allow you to draw vectors and points on the
screen.
a. Vectors.
"V" command. This causes a new vector to start being
displayed with one end where the cursor is now. The other end of the
vector will follow the cursor until another command is given.
"I" command. This stops the current vector that was started
by a "V" command from following the cursor and fixes where it is.
The "I" command doesn't do anything for you if it doesn't follow a
"V" command.
"P" command. This deposits a point at the location of the
cursor.
b. Free hand. To stop drawing free hand points or vectors,
type altmode.
"FV" command. After you have typed this command, PIXPEN
automatically starts a new vector (as if you had typed "V") every
time you move the cursor some minimum distance from where the last
vector was started. This minimum distance is set by the "M" command.
(See "Miscellaneous commands".)
"FP" command. This is the same as "FV" command, except that
it deposits points instead of drawing vectors.
2. Miscellaneous commands.
a. Delete -- "D" command. Delete the last vector or point
displayed (if a vector, then the one following the cursor).
b. Zero -- "Z" command. Clear the display.
c. Modify constants -- "M" command. This command is used to
modify a number of program constants. After you type it, you will be
asked several questions. To ignore any question, type carriage
return to it. Following are the modifications you may make:
Character size. This is the size of characters that you will
get in the text submode. Size may be 1 through 7.
Character quality. A "B" (Best) response here will get you
the best quality characters currently available, packed only 1 to a
word. An "M" (Marginal) response will get you inferior characters,
but packed 5 to a word. PIXPEN is initialized with "best"
characters.
Assumed extension. If you type some extension here (like
"DPY"), then this extension will get tacked onto every file name you
type (see Input/Output). PIXPEN is initialized with no assumed
extension.
Free hand vector length. This wants to be a number in screen
raster units (see "FV" command). There are 1000 (decimal) raster
units in the width (heigth) of the display screen. This number
starts out at 10.
Grid size. If the grid size is greater than 1, then PIXPEN
acts, for all intents and purposes, as if the display raster unit
were the grid size. The grid size is expressed in terms of normal
(real) display raster units. This number starts out at 1.
d. Give me information -- "=" command. This causes several
internal program parameters to by typed, such as maximum display
buffer size (see Initialization), number of vectors in buffer, and X
and Y coordinates of the cursor.
3. Input/Output.
Following are the commands to use for getting displays to and from
the disk. In all cases, except for the "B" command, if you type
carriage to the "file name?" query, the command has no action.
a. Read display -- "R" command. This causes (1) any current
display to be cleared; (2) PIXPEN to ask you for a file name; (3)
PIXPEN to stick the current assumed extension (if any) onto the file
name; and (4) the resulting file to be read from the disk and
displayed.
b. Append display -- "A" command. This causes (1) PIXPEN to
ask you for a file name; (2) PIXPEN to stick the current assumed
extension (if any) onto the file name; and (3) the file to be read
from the disk and appended to your current display, to make one large
display.
c. Background display -- "B" command. Sometimes it is handy
to use one display as a template for drawing another display, as in
drawing successive frames in a movie. The "B" command causes a
display to be read as with the "R" command, except that (1) the
original display does not dissappear; and (2) the background display
cannot be edited in any way. To make the background go away, type
"B" and then carriage return to the "file name?" query.
d. Write display -- "W" command. This causes (1) PIXPEN to
ask you for a file name; (2) PIXPEN to stick the current assumed
extension (if any) onto the file name; and the display to be written
onto the disk under that file name. This command does not affect any
display buffer in any way.
4. Edit submode.
Type "E" to enter this submode, which has a set of commands all its
own. The purpose of the edit submode is to provide facilities for
editing the display after it has been created. While you are in
edit submode, there is always some vector that is the "current"
vector, or the vector under consideration. PIXPEN tells you which
vector this is by flashing it. Any edit command may be preceeded by
a number, which acts multiplicatively on the command it preceeds. For
instance, typing "5B" is the same as typing "BBBBB".
a. Back up -- "B" command. Back up the current vector in the
display buffer.
b. Forward -- "F" command. Advance the current vector in the
buffer.
c. Delete -- "D" command. Delete the vector under
consideration. This actually deletes the vector, reclaiming the
storage it occupied.
d. Change -- Change the vector under consideration. After
typing this command, type the letter corresponding to a vector type:
"V" for a visible vector, "I" for an invisible vector, or "P" for a
point. If you typed a number before the "C", then that many vectors
get changed to visible, invisible, or point. For example, if you
typed "3CI", and the three vectors in the buffer starting with the
current one were visible, then they would all dissappear.
e. Altmode -- Exit edit submode.
5. Text submode.
As soon as you type "T", you enter text submode, and a second, text
cursor (which looks much like the system typout cursor) then appears
to the right of the regular cursor. Any characters you type will be
entered into the display. Typout will happen as with the system
typout, but with the left-hand margin at the position of the cursor.
This affects the interpretation of both carriage return and tab. All
characters are taken literally, with the following exceptions:
a. Backspace (BS key). Erases the last character typed and
moves the text cursor one character one position left, unless this
cursor is already at the left-hand margin defined by the main cursor.
In the latter case, backspace has no affect.
b. <ctrl 1> line feed (hold down the control 1 key and type
line feed). This erases all the characters on the line you were
typing and moves the text cursor to the left-hand margin defined by
the main cursor. This has the effect of typing many backspaces.
c. Altmode. This causes all the text you have typed to be
saved, erases the text cursor, and exits you from text mode.
APPENDIX I. ERRORS
There are only three kinds of errors that you can make that PIXPEN
will tell you about explicitly, and are as follows:
1. Illegal parameter specification.
This may occur at initialization in specifying the buffer size, or in
an "M" command in specifying the character size, free hand vector
length, or raster size. You will immediately be informed of your
misdeed and be given an opportunity to mend your ways.
2. Illegal command.
If you type an illegal command at the upper level (i.e., not in edit
submode) then your illegal command preceeded by a question mark will
be displayed in large size characters in the upper right-hand corner
of the screen until you type a legal command.
3. Display buffer overflow.
If by either reading a file, entering vectors, or entering text
PIXPEN tries to overflow your display buffer, it will stop itself and
display in large letters across the screen "DISPLAY BUFFER OVERFLOW
TYPE CR TO CONTINUE". You can continue editing your buffer as
before, but every time you try to add to the buffer in any way, this
error will recur, until you have made some room in the buffer by
either deleting some vectors or by zeroing the buffer.
APPENDIX II. SUMMARY OF COMMANDS
1. Drawing
a. Vectors
"V" -- Visible vector.
"I" -- Stop visible vector; invisible vector.
"P" -- Point.
b. Free hand
"FV" -- Free hand vectors.
Altmode -- Stop free hand vectors.
"VP" -- Free hand points.
Altmode -- Stop free hand points.
2. Miscellaneous
"D" -- Delete the last vector in the buffer.
"Z" -- Zero the buffer.
"M" -- Modify program parameters.
"=" -- Give me information.
3. Input/Output
"R" -- Replace the buffer by reading from the disk.
"A" -- Append to the buffer by reading from the disk.
"B" -- Read a background display.
"W" -- Write the buffer onto the disk.
4. Edit submode
"B" -- Back up in the buffer.
"F" -- Go forward in the buffer.
"D" -- Delete the vector you are looking at.
"C" -- Change the vector you are looking at:
"CV" -- Change it to visible vector.
"CI" -- Change it to invisible vector.
"CP" -- Change it to point.
Altmode -- Exit edit submode.
5. Text submode
Backspace -- Erase one character.
<ctrl 1> line feed -- Erase current line.
Altmode -- Exit text submode.